BBS in a Box 7

home *** CD-ROM | disk | FTP | other *** search

/ BBS in a Box 7 / BBS in a Box - Macintosh - Volume VII (BBS in a Box) (January 1993).iso / Files / Tele / T / Terminal 1.7.cpt / Terminal.doc < prev next >

Wrap

Text File | 1989-11-06 | 38.5 KB | 1,025 lines | [TEXT/QED1]

=========================================================================== "Terminal" A Serial Communication Program For The Macintosh =========================================================================== Version 1.7 (November 1989) ___________________________________________________________________________ INTRODUCTION "Terminal" is a serial communication program for the Macintosh computer. Features are: * Fast display. No characters are lost, even at 9600 Baud with text capture to disk enabled. (For most commercial programs this only holds for short term until the serial input buffer is full.) * Capture buffer, so that the last 32768 (default, can be configured) characters are always available in the scrolling terminal window. The buffer can be saved as TEXT file to disk. Very fast scrolling to move around in the buffer. * Text capture to disk, so that everything received or transmitted is saved automatically to a TEXT file on disk. * Send TEXT files from disk. Wait for prompt string before sending line, delay after each line, delay after each character, XON/XOFF, CTS or no handshake. * Binary file transfer using X-Modem protocol (checksum, CRC or 1K options), Y-Modem batch or CompuServe-B protocol (up- and download). Automatic recognition of MacBinary (I and II) file format. The effective speed of X-Modem file transfers is faster than most commercial programs. Useful if transferring files between two direct connected computers at fast speed. * Built-in C interpreter with a rich set of intrinsic functions to execute scripts from TEXT files. Scripts can be as simple as modem setup, dial or auto-logon, but can also be used to program a complete BBS. * Very compact program. Only uses 57K on disk and can run in a 128K partition under MultiFinder. * Complete non-modal program (even during file transfers), and runs in background under MultiFinder. * The program is free. * Source code is available (written in THINK C 3.02). ___________________________________________________________________________ CONFIGURATION "Terminal" was developed (in THINK C 3.02) and tested on a Macintosh Plus and on a Macintosh IIcx with System 6.03. The program is MultiFinder aware and can work in the background. 128K ROMs (or newer) are required, so "Terminal" will not run on "old" Macs. Please use the most recent system software. The so-called "RAM serial driver" is not included as a resource, it should be in the ROM. The "ScriptUtil" trap is is used to map the "Option" key into the control key, and this trap was not available on older Systems. ___________________________________________________________________________ FILES AND FOLDERS * "Terminal" the application, can be anywhere on your disk. * "Terminal Settings" is created by "Terminal" in the System folder to store the options selected. If this file is not found when "Terminal" starts up default options will be used. * "Terminal Scripts" is a folder that should be created in the same folder as the "Terminal" application. All scripts (a script is a TEXT file with a suffix of ".s") in this folder will be included in the "Scripts" menu for easy execution. If this folder does not exist, all scripts in the same folder as the "Terminal" application will be included in the "Scripts" menu. * The "Terminal options" menu can be used to select a start-up script, that will be automatically executed when the application is started. This script can be anywhere on the disk. By default there is no start-up script. * For use with Y-Modem batch and CompuServe-B file transfers a folder must exist on the disk where all downloads and uploads using these protocols will look for and store files. This folder can be selected by using the "File transfer options" menu option. The default folder is the same as the folder containing the "Terminal" application. This folder is also the default folder used by script file commands. ___________________________________________________________________________ THE TERMINAL WINDOW There is a fixed size window with 24 lines and 80 columns (default values, can be configured). The window can be moved anywhere on the screen. A vertical scroll bar allows fast moving around in the last 32768 (default value, can be configured) characters received. If a new character is received the text automatically scrolls to the end. Everything received is displayed in the terminal window, even if the window is not the frontmost or if the application was switched out under MultiFinder. The name of the window will be "Terminal" if no script is executing, otherwise the window name will be the same as the name of the script file. To cancel a running script select it again under the corresponding menu item. If the terminal window is frontmost everything typed on the keyboard is transmitted. If the local-echo option is selected it is also echoed to the window. To send control characters the "Option" key can be used if there is no "Control" key. The "Command" key can be used as usual to select menu commands. After file transfers a statistics message is displayed in the top area of the window showing how much bytes were transferred in how much time. This area is also used to display error messages. If a message is displayed a button appears to the left of it. Clicking this button will erase the message and the button. Note that such a message is not a modal dialog but will stay as long as there is no new message or until it is cleared. Meanwhile the program continues its normal operation. During file transfers a dialog window (this is a non-modal window, not a modal dialog box, and can be moved around or deselected, and all menu commands are still available while this window is up) is displayed. This dialog window shows the progress of the file transfer and has a "Cancel" button. By clicking in this "Cancel" button the file transfer can be aborted. The file transfer can also be canceled by selecting the corresponding menu item. Characters received in terminal mode are filtered using the following criteria (this is what I consider basic TTY emulation): * All bytes received will get their most significant bit stripped to make 7 bit ASCII characters. * A "CR" character (carriage return, ASCII 13) will move the cursor to the first position in the next line. * A "Backspace" character will erase the last character received and move the cursor one position to the left, but will never move to the previous line. The code to be recognized as "Backspace" can be chosen (see "Options menu"). If TEXT file capture is on, all characters are saved as received in the file including the "Backspace" characters. * A "TAB" character (ASCII 9) will be accepted (and saved if TEXT file capture is on) but displayed as a space character. * Two consecutive "CAN" (control-X, ASCII 24) are recognized as a signal to abort text file sends or X/Y-Modem file transfers. * All other control characters are ignored and only characters with ASCII codes higher then 32 and lower than 126 are accepted (printable characters). * If lines longer than 80 characters are received a "CR" will be inserted automatically after every 80 characters, and this "CR" will also be saved to disk if TEXT capture is on. ___________________________________________________________________________ THE "FILE" MENU SAVE CAPTURE BUFFER A standard file dialog is presented (if the capture buffer is not empty) allowing to save the contents of the capture buffer to disk as a TEXT file. The TEXT file creator can be changed using the "Text capture option" item in the "OPTIONS" menu. TEXT CAPTURE A standard file dialog is presented allowing to create the TEXT file where all further input or output will be saved. The TEXT file creator can be changed using the "Text capture option" item in the "OPTIONS" menu. The menu text will change to outlined and expanded, so that when selected again the capture file will be closed. The file is also automatically closed when quitting the program. TEXT SEND A standard file dialog is presented to select a TEXT file. The file contents is sent using the options that can be selected in the "TEXT file transfer options..." item of the "Options" menu. The menu text will change to outlined and expanded, so that when selected again the transmission will be canceled. If two control-X characters are received the transmission is also canceled. FILE RECEIVE If Y-Modem batch is active (see "Binary File Transfer Options" menu), the file transfer starts immediatly. During a batch session more than one file my be received. All files received are stored in the folder selected by the "Binary File Transfer Options" dialog. If MacBinary file format is enabled, the file name used will be the name from the MacBinary header if this name does not yet exist, otherwise the name from the Y-Modem header (block 0) will be used, and if a file with this name exists it is deleted first. If MacBinary is disabled the file name from the Y-Modem header (block 0) is used, and if a file with this name exists it is deleted first. If no batch is choosen a standard file dialog is presented to create a file to be used for binary file receive using X-Modem protocol. The X-Modem protocol file receive session is started. If MacBinary file format is enabled, the file name used will be the name from the MacBinary header if this name does not yet exist, otherwise the first chosen name will be used. Note that for CompuServe-B protocol file transfers there is no need for this menu option as the transfers will be initiated by the host and the host will prompt you for the file name on your computer. FILE TRANSMIT A standard file dialog is presented to select the binary file to transmit using X-Modem or Y-Modem protocol. If the MacBinary file format is enabled the file is sent in MacBinary II format. In Y-Modem batch only one file can be send in a session. Note that for CompuServe-B protocol file transfers there is no need for this menu option as the transfers will be initiated by the host and the host will prompt you for the file name on your computer. MAKE MACBINARY FILE Use this utility option to create a MacBinary II file from any other file on your disk. Normally this need not to be used, because the FILE TRANSMIT menu command will create the MacBinary II file on the fly while transmitting. EXTRACT FROM MACBINARY FILE Use this utility option to extract a file from a MacBinary I or MacBinary II file on your disk. This is useful if you have forgotten to enable automatic MacBinary recognition and you have already downloaded a file. QUIT To quit and return to the Finder use this option or click in the close box of the terminal window. ___________________________________________________________________________ THE "EDIT" MENU Most items are only there for desk accessories. Only the following is used: CLEAR CAPTURE BUFFER This will clear the capture buffer and the terminal window. DEBLOCK SEND This kills any outstanding serial write request. It might be useful if the program has received an XOFF, but never got the XON. ___________________________________________________________________________ THE "OPTIONS" MENU The options selected in the following dialogs are saved in a file in the system folder, so that they are again available when the program is started at a later time (the file name is "Terminal Settings"). If no options file is found in the system folder when the program is started, default values will be used. COMMUNICATION Baud rate: 300 to 56700 Baud. Data bits: 7 or 8. Stop bits: 1 or 2. Parity: even, odd or none. Port: Modem or printer. Don't drop DTR when quitting: useful if you don't want the modem to hang-up when you quit the program. Note: During binary file transfers the data bits are set to 8 bits. When the transfer is finished the original value is restored. TEXT FILE SEND Wait for prompt before sending next line: If this option is checked the program will wait for the prompt string (this can be more than one character) before sending the next line while sending TEXT files. Delay after each line sent: If this option is checked the program waits for the specified number of ticks (1/60 second) before sending the next line while sending TEXT files. Delay after each character sent: If this option is checked the program waits the specified number of ticks (1/60 second) before sending the next line while sending TEXT files. Handshake: Possible choices are XON/XOFF, CTS (useful if sending a TEXT file to a printer, or a terminal node controller for packet radio using hardware handshake) or no handshake. BINARY FILE TRANSFER MacBinary: use and recognize MacBinary file format in file transfers (Note that pure TEXT files are never sent as MacBinary). CIS-B: recognize and use CompuServe-B protocol for file transfers. Path for up- and downloads: folder name used for CIS-B up- and downloads (because the host will only prompt for the file name on your computer but not the path name) and for Y-Modem batch file downloads (where only the file name is in the header block). X-Modem or Y-Modem: * CRC If not checked "classic" X-Modem with simple checksum and 128 Byte blocks will be used. The "1K" options are disabled. If checked CRC error checking will be used and the "1K" options are enabled. * 1K off 128 Byte blocks are used. aut 128 or 1024 Byte blocks are used automatically and where appropriate. During the initial handshaking phase the single character "C" is used. This is the "official" way of doing it. CK 1024 Byte blocks are used if during the initial handshaking phase the two character sequence "CK" is used (this is used by Red Ryder 10.3 and perhaps others). * batch off No batch protocol is used, i.e. this is X-Modem. Y "Official" Y-Modem batch protocol is used. RR A variant of the Y-Modem batch protocol is used where there is no new handshaking phase after the header block (block 0) has been sent (this is used by Red Ryder 10.3 and perhaps others). * timeout Select the value 5, 10, 15 or 20 seconds. TERMINAL Echo: local (display keyboard characters), remote (retransmit received characters). Display and capture: if checked the capture window and buffer are active, else nothing is displayed nor captured. AutoLF: If this option is checked a linefeed character will be send after each carriage return character. Start-up script: Any script can be selected to be executed automatically when the "Terminal" application is started. OTHER Text capture file creator: file creator for TEXT files used for saving the capture buffer or by the "Text file capture" option. So if you double- click on these files your favorite text editor program is automatically called. File type and creator for non-MacBinary files: if automatic MacBinary file format recognition is not enabled, or if the file received is not a valid MacBinary file, this type (default is 'TEXT') and creator are used for the new file. Code for "backspace" key: ASCII code send by pressing the "Backspace" key, and also the ASCII code recognized as "Backspace" code while receiving. Code for "`' key: ASCII code send by pressing the "`" key. This can be used to make an "ESC" key (ASCII 27) on keyboards that don't have an "ESC" key. Note that for sending control characters (e.g. cntl-C) the "Option" key can be used on the keyboard if there is no control key. ___________________________________________________________________________ THE "SCRIPTS" MENU A script is a TEXT file containing a program written in "Terminal" script language, which is a subset of the C language. Scripts are interpreted by "Terminal", there is no compilation step involved. The easiest way to maintain scripts is to use a desk accessory TEXT editor. If you use a word processor, you must save the script files as pure TEXT, not in the native format of the word processor. The first item in this menu can be used to select any script file on your disk using a standard file dialog box. Only TEXT files with a suffix of ".s" are considered to be scripts. The other items depend on what "Terminal" found in it's folder when it was started. If a folder "Terminal Scripts" exists in the application folder, all script files found there are included in the menu. If no such folder exists all script files found in the application folder are listed in the menu. Selecting a script in the menu will start it. The menu item name changes to outlined and expanded. To cancel a running script simply select it's menu item again. If a script is running the terminal window's name is set to the name of the executing script. Only one script at a time can be executing. Any script can be selected to execute automatically when "Terminal" is started by using the "Terminal Options" menu. ___________________________________________________________________________ THE SCRIPT LANGUAGE The script language interpreted by "Terminal" is a subset of C with many specialized intrinsic (built-in) functions. Please read a C reference book to learn the C syntax, or see the enclosed script examples to get a feeling of the language. I will not write a book about programming in C here, only tell you the essentials. PROGRAM A program is recognized as a script if it is in a TEXT file, and if the file name ends in ".s". Spaces, tabs and carriage return characters are considered to be white space. No identifier and no keyword can be separated by white space. A program consists of: comments, global variable definitions and function definitions. Everything included between "/*" and "*/" is considered a comment and will not be interpreted. Comments cannot be nested. The "/*" and "*/" are not recognized as comment delimiters inside string or character constants. Global variables are those variables that are known to all functions, unless their names are reused as local variables. Global variables can be initialized using any expression that involves either constants or other globals that are already defined at that point. Function definitions can appear in any order and their must be at least one function called "main" with no parameters. It is this function that is called when the script is started. Every function is supposed to return an integer value as result. Functions can be called recursively. There are many built-in functions that are already defined when the script is started. This is an example of a simple script that displays the message "The number is 123" in the terminal window: int Number = 123; /* This is a global variable */ main () /* Every script must have a main() function */ { /* display() is a built-in function */ display("The number is %i\r", Number); } IDENTIFIERS An identifier is a sequence of letters and digits; the first character must be a letter. The underscore "_" counts as a letter. An identifier can be of any length up to 255 characters. All characters are significant and are case sensitive. There are three types of identifiers: keywords, function names, variable names. The keywords are: "break", "char", "else", "for", "if", "int", "return", "while". CONSTANTS An integer constant is a sequence of decimal digits, or 0x followed by up to 8 hexadecimal digits. An integer value is represented internally by 4 bytes (32 bits). A minus sign before a constant is considered as an unary operator, not a part of the constant itself. A character constant is a sequence of 1 to 4 characters enclosed in single quotes. Character constants are converted to integer values, the byte values corresponding to the ASCII codes of the characters. A string constant is a sequence of characters enclosed in double quotes. String constants are automatically terminated by a NULL character. The value of a string constant is the address of the first character. Some examples of valid constants: 1234567 0xABCD1234 'a' 'TEXT' "An apple a day keeps troubles away" In character and string constants the backslash "\" is used as an escape sequence according to the following table: LF 0x0A \n TAB 0x09 \t FF 0x0C \f BELL 0x07 \a BS 0x08 \b CR 0x0D \r VT 0x0B \v NULL 0x00 \0 any 0x.. \x.. (2 hex digits) If the character following a backslash is not one of those specified the backslash is ignored. This can be used to represent the backslash itself, to put a single quote into a character constant or to put a double quote into a string constant. Some examples; "Going to the next line...\r" '\0' "This is a single backslash: \\" "\"Hello world!\"" '\'' '\x03' /* That's a control-C */ VARIABLES There are four types of variables: characters, integers, pointers and arrays. Integers represent 32 bit signed values and characters 8 bit signed values. Pointers hold the 32 bit address of integers, characters or other pointers. Arrays are more or less equivalent to pointers. The following examples show how variables are defined: char c; /* "c" is a character variable */ int n; /* "n" is an integer variable */ char *ptr; /* "ptr" is a pointer to characters */ char **hdl; /* "hdl" is a pointer to character pointers */ int *p; /* "p" is a pointer to integers */ int **q; /* "q" is a pointer to integer pointers */ char a[80]; /* "a" points to an array of 80 characters (80 bytes) */ int b[10]; /* "b" points to an array of 10 integers (40 bytes) */ char *c[5]; /* "c" points to an array of 5 character pointers (20 b) */ int *d[5]; /* "d" points to an array of 5 integer pointers (20 b) */ Variable declarations can be grouped together like this: char c, *ptr, **hdl, a[80], *c[5]; int n, *p, **q, b[10], *d[5]; Variables can be initialized using any legal expression, not only constants. Arrays can only be initialized at the global level, i.e. outside of function definitions. Initialized arrays must not include their size between the square brackets, the size is calculated based on the initializing values. char c = 'x'; int n = -123; int m = n * 10; /* "m" is set to -1230 */ char message[] = "This is a character string"; char *messages[] = /* Array of strings */ { "This is string #1", "Another string", "and so on..." }; int a[] = { 1, 2, 3, 4, 5 }; /* Array of 5 integers */ The are no logical variables. Everything that is not zero is considered to be true. EXPRESSIONS The following is a list of the supported operators that build up an expression. The list is by increasing precedence. Normally operators group left to right unless otherwise noted below. Note that the assignment is an operator, that an expression may contain several assignments, and that an assignment returns a value. Logical and numerical operators can be freely mixed, everything not zero is considered to be true. The precedence level can be changed by using parentheses. The boolean operators will return 1 as true. Assignment = (right to left) Logical or || Logical and && Equal, not equal == != Relational operators < <= > >= Add, subtract + - Multiply, divide, modulo * / % Logical not, increment, decrement, unary minus, indirection, address of ! ++ -- - * & (right to left) Function call, array element () [] The increment or decrement operators can be used before or after a variable. If the operator comes before the variable (preincrement, predecrement) the variable is incremented, or decremented, and then the variable's value is used in the expression evaluation. If the operator comes after the variable (postincrement, postdecrement) the current value of the variable is used in the expression evaluation, and then the variable is incremented, or decremented. Array subscripts start with 0. There is no runtime check of array boundaries. An array subscript can be any valid expression. Some examples: char a[80]; c = a[0]; /* The first element */ c = a[79]; /* The last element */ c = a[i = (79 - Func(x)*3)]; /* Expression as subscript */ For pointer arithmetic the following rules apply: if an integer value is added or subtracted from a pointer (a pointer is an address) then the integer value is first scaled depending on what the pointer is pointing to: 1 for characters, 4 for integers, 4 for pointers. If two pointers are subtracted the result is scaled in the same way and yields an integer value representing the number of objects separated by the two pointers. The two pointers must point to the same type of objects. A function identifier without a parameter list in an expression results in the address of the function being used. If there is a parameter list, the function is called and the integer value returned by the function is used. Functions can also be called indirectly, using any expression that yields a valid function address followed by a parameter list. Some examples: int pf; /* "int" can be used as function pointer */ int i; pf = Func; /* "pf" will contain address of function "Func" */ i = Func(); /* "i" gets function result */ i = (pf)(); /* "i" gets function result */ FUNCTIONS A function definition can only occur in the outer, global level. A function cannot be defined inside another function. All functions are supposed to return integers. A function definition consists of the function name, followed by a parameter definition list enclosed in parentheses, followed by a compound statement. The parameter definition list describes the function parameters. These parameters are considered as local variables inside the function. Example: /* The following function takes 3 parameters: a character, an integer and a character pointer. It always returns the value 123. */ Function (char c, int i, char *p) { /* ... */ return 123; } A function call consists of the function name followed by a parameter list. The parameter list is a comma separated list enclosed in parentheses of expressions. All parameters are passed by value. There is no verification if the number of parameters is correct or if the values passed to a function correspond to the types of the declared parameters. Example: i = Function ('x', 4567 + x, "Hello"); STATEMENTS A compound statement starts with an open brace "{" and terminates with a closing brace "}". There is an optional variable definition part followed by a list of statements. Variables defined inside a compound statement are local to that compound statement (block). A statement can be: compound statement expression ; if ( expression ) statement if ( expression ) statement else statement while ( expression ) statement for ( opt expr1 ; opt expr2 ; opt expr3 ) statement break ; return ; return expression ; ; The two forms of the conditional statement are: if ( expression ) statement if ( expression ) statement else statement In both cases the expression is evaluated and if it is nonzero, the first substatement is executed. In the second case the second substatement is executed if the expression is 0. The "else" ambiguity is resolved by connected an "else" with the last encountered "else"-less "if". The "while" statement has the form: while ( expression ) statement The substatement is executed repeatedly so long as the value of the expression remains nonzero. The test takes place before each execution of the statement. The "for" statement has the form: for ( opt expr1 ; opt expr2 ; opt expr3 ) statement This statement is equivalent to: expression1 ; while ( expression2 ) { statement expression3; } Thus the first expression specifies initialization for the loop, the second specifies a test, made before each iteration, such that the loop is exited when the expression becomes 0; the third expression often specifies an incrementation which is performed after each iteration. Any or all of the expressions may be dropped. A missing expression2 makes the implied "while" clause equivalent to while(1); other missing expressions are simply dropped from the expansion above. The statement break ; causes termination of the smallest enclosing "while" or "for" statement; control passes to the statement following the terminating statement. A function returns to its caller by means of the "return" statement, which has one of the forms: return ; return expression ; In the first case the returned value is undefined. In the second case the value of the expression is returned to the caller of the function. If required, the expression is converted to an integer. Flowing off the end of a function is equivalent to a return with no return value. The null statement has the form ; A null statement is useful to supply a null body to a looping statement such as "while". ___________________________________________________________________________ INTRINSIC FUNCTIONS Intrinsic functions are built-in and need not to be defined in the script. They can be called by any script. All file access functions operate on the CIS-B up- and download folder, which is the folder that can be set with the "Binary file transfer options..." menu item. File names can be up to 31 characters long. All formatting functions (display, format, type) use a template string to specify the formatting to be done on the following parameters. Format specifiers begin with the character % and include zero or more of the following conversion specification elements (optional fields are in brackets): % [option flags] [field size] conversion Some of these elements are optional, but if present, they must be specified in the order in which they are described below. Option flags (optional): - Left adjust output in field, pad on right (default is to right justify). 0 Use zero (0) rather than space for the pad character Field size specification (optional): The minimum field width, expressed as a decimal integer. The corresponding parameter will be printed in a field at least this wide. Conversion characters (required) c Parameter is a character i Parameter is an integer s Parameter is a null terminated string % Print a %, no parameter used The format specification elements must correspond to the following parameters. Some examples: char k, m[80]; int n; type("Unrecognized character %c on line %i of file %s\r", k, n, m); autolf Set the auto linefeed flag on or off call: autolf(flg) flg: zero means off, nonzero means on beep Macintosh system beep call: beep() catalog Return file info call: err = catalog(i,name,&type,&dsize,&rsize,&cdate,&mdate) err: Macintosh file system error, 0 if no error i: If 0, then name must be specified and information about the file with that name is returned, if it exists. If non-zero information (including file name) about the i-th file in the folder is returned. name: Pointer to character string of at least 32 characters. This is the file name (specified or returned depending on the value of i). type: Integer (4 bytes). File type. dsize: Data fork size in bytes. rsize: Resource fork size in bytes. cdate: Creation date in seconds. mdate: Modification date in seconds. date Convert seconds from Macintosh clock to date and time call: date(sec, &yr, &mo, &da, &ho, &mi, &se, &dw) sec: seconds yr: year (1904..20xx) mo: month (1..12) da: day (1..31) ho: hour (0..23) mi: minutes (0..59) se: seconds (0..59) dw: day of week (1..7, Sunday is 1) display Display in the terminal window call: display(templ, ...) templ: template string ...: variable number of arguments (maximum 9) download Download (receive) a binary file using X-Modem protocol call: err = download(name, bin) err: error code returned. 0 if Ok. 1 if timeout. 2 if cancel. 3 if abort (2 consecutive control-X characters received). All other values are Macintosh file system errors. name: File name for new file bin: non-zero to recognize and use MacBinary format format Formatted conversion of values into a string call: format(str, templ, ...) str: string for result templ: template string ...: variable number of arguments (maximum 8) free Dispose of the memory allocated by the new() function call: free(p) p: pointer returned by previous call to new() function getcts Get current state of CTS input line (*** not yet implemented ***) call: onoff = getcts() onoff: 0 if negated, 1 if asserted lecho Set the local echo flag on or off call: lecho(flg) flg: zero means off, non-zero means on move Move bytes from source to destination call: move(src, dest, cnt) src: source character pointer dest: destination character pointer cnt: number of bytes to move new Allocate memory call: p = new(size) p: pointer to memory, or 0 if not enough memory available size: number of bytes to allocate nextline Wait for the next line received over the serial input port call: err = nextline(line, t) err: 0 line received, 1 timeout, 2 cancel, 3 abort (2 consecutive control-X characters received) line: string to hold line t: timeout value in ticks (1/60th of second) pause Pause for specified amount of time call: err = pause(t) err: 1 timeout, 2 cancel. t: timeout value in ticks (1/60th of second) prompt Wait for a prompt string to come over the serial input port call: err = prompt(str, t) err: 0 string received, 1 timeout, 2 cancel, 3 abort (2 consecutive control-X characters received). str: string to wait for (case sensitive) t: timeout value in ticks (1/60th of second) recho Set the remote echo flag on or off call: recho(flg) flg: zero means off, non-zero means on save Set the save & display flag on or off call: save(flg) flg: zero means off, non-zero means on send Send a text file over the serial output port call: err = send(name) err: error code returned. 0 if Ok. 2 if cancel. 3 abort (2 consecutive control-X characters received). All other values are Macintosh file system errors. name: File name setdtr Set DTR output line call: setdtr(onoff) onoff: 0 to negate, 1 to assert setup Serial communications port setup call: err = setup(baud, data, parity, stop, port, dtr) err: 0 if no error baud: 0=300, 1=600, 2=1200, 3=2400, 4=4800, 5=9600, 6=19200, 7=38400, 8=57600 baud (or -1 for no change) data: 0=7, 1=8 data bits (or -1 for no change) parity: 0=no, 1=even, 2=odd parity (or -1 for no change) stop: 0=1, 1=2 stop bit (or -1 for no change) port: 0=modem, 1=printer port (or -1 for no change) dtr: 1=don't drop DTR when quitting (or -1 for no change) stack Return free memory available for script heap and stack call: bytes = stack() bytes: Combined free heap and stack space strcmp Compare two strings (not case sensitive) call: res = strcmp(str1, str2) str1: first string str2: second string res: 0 if strings are equal, positive if str1 > str2, negative if str1 < str2 terminal Set terminal parameters call: terminal(lecho, recho, autolf, save) lecho: Local echo flag (or -1 if no modification) recho: Remote echo flag (or -1 if no modification) autolf: Auto line feed flag (or -1 if no modification) save: Save & capture flag (or -1 if no modification) time Return seconds from Macintosh clock call: sec = time() type Send a string over the serial output port call: type(templ, ...) templ: template string ...: variable number of arguments (maximum 9) upload Upload (transmit) a binary file using X-Modem protocol call: err = upload(name, bin) err: error code returned. 0 if Ok. 1 if timeout. 2 if cancel. 3 abort (2 consecutive control-X characters received). All other values are Macintosh file system errors. name: File name bin: non-zero to recognize and use MacBinary format ___________________________________________________________________________ THE CONFIGURATION RESOURCE Some program parameters are kept in a configuration resource in the "Terminal" application. These parameters cannot be changed while the program is running, so there is no corresponding dialog in the "Options" menu. You must use "ResEdit" to change those parameters. The resource name is "CNFG" and the id is 128. Offset Length Description 0 2 Font number (must be a monospaced font, e.g. Monaco is 4) 2 2 Font size (e.g. 12) 4 2 Lines in terminal window (e.g. 25) 6 2 Columns in terminal window (e.g. 80) 8 4 Size of terminal buffer in bytes (e.g. 32768) 12 4 Size of serial input buffer in bytes (e.g. 4096) 16 4 Size of serial output buffer in bytes (e.g. 256) 20 4 Size of script memory in bytes (e.g. 16384) In "ResEdit" this may look like this: 000000 0004 000C 0019 0050 000008 0000 8000 0000 1000 000010 0000 0100 0000 4000 On a Macintosh Plus Monaco 9 with 24 lines of 80 columns fills the entire screen, but on a Macintosh IIcx with an Apple color monitor Monaco 12 with 25 lines of 80 columns fills the entire screen. Note that if the buffer sizes are changed the "SIZE" resource must be changed accordingly under MultiFinder, otherwise the program may not get enough memory. Yoy can use the "About..." menu item to check for available memory while "Terminal" is running. ___________________________________________________________________________ COMMENTS AND SUGGESTIONS Send any comments, bug reports and suggestions to my address: Erny Tontlinger 33, route d'Arlon L-8410 Steinfort Luxembourg or via electronic mail to my CompuServe account 73720,2200. I'am a radio amateur, so you can reach me also via the packet radio network at LX1YZ @ LX0PAC. This program is absolutely free, including the C sources. So do with it what you like, but please include the documentation if you give it away.